home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / tge120.zip / TGE.DOC < prev    next >
Text File  |  1993-05-05  |  74KB  |  1,682 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.          The Graphics Engine version 1.20 Documentation
  7.                            May 5, 1993
  8.  
  9.  The Graphics Engine software and manual are copyright (c) 1993
  10.           by Matthew Hildebrand.  All rights reserved.
  11.  
  12.  
  13.  
  14.  
  15. Topics covered in this document:
  16. ───────────────────────────────
  17.  
  18.      INTRODUCTION
  19.      MAJOR FEATURES OF THE GRAPHICS ENGINE
  20.      SYSTEM REQUIREMENTS
  21.      PACKING LIST
  22.      RELEASE NOTES FOR VERSION 1.20
  23.      INCORPORATING THE GRAPHICS ENGINE
  24.      THE GRAPHICS ENGINE'S GRAPHICAL FUNCTION SET
  25.      VIEWPORTS AND CLIPPING
  26.      FONTS
  27.      USING THE MOUSE
  28.      THE GRAPHICS ENGINE'S MOUSE FUNCTION SET
  29.      WRITING GRAPHICS DRIVERS
  30.      TERMS OF USAGE AND DISTRIBUTION
  31.      CONTACTING THE AUTHOR
  32.      OBTAINING THE GRAPHICS ENGINE
  33.      REVISION HISTORY
  34.      ACKNOWLEDGEMENT
  35.      LEGAL MUMBO JUMBO
  36.  
  37.  
  38.  
  39.  
  40. INTRODUCTION
  41. ────────────
  42.  
  43.      The Graphics Engine is the result of my efforts to construct
  44.      a library of routines designed to make writing C/C++
  45.      graphics applications easier.  I have used it in my own
  46.      programs with excellent results.
  47.  
  48.      TGE allows the DOS programmer to easily access any graphics
  49.      mode, without having to do special coding for each; the
  50.      complications involved with supporting more than one
  51.      graphics mode are removed.  TGE also provides remarkable
  52.      flexibility and expandability through its modular design.
  53.  
  54.  
  55.  
  56. MAJOR FEATURES OF THE GRAPHICS ENGINE
  57. ─────────────────────────────────────
  58.  
  59.      TGE provides a simple, standard interface with which
  60.      programs may access a powerful library of graphical
  61.      functions.  As an added bonus, this library occupies much
  62.      less memory than other commercial packages do, such as
  63.      Borland's BGI.
  64.  
  65.      TGE supports device-independence using loadable drivers,
  66.      loadable fonts, viewports, interrupt-driven definable mouse
  67.      pointer services, a large number of mouse routines, and an
  68.      extensive graphical function set.
  69.  
  70.      TGE's use of loadable graphics drivers means that all code
  71.      and data necessary to handle a certain graphics mode is
  72.      stored in a disk file.  When a program runs, this file will
  73.      be loaded into memory and the code it contains will be made
  74.      available.  Consequently:
  75.         - Support for more graphics modes may be added simply by
  76.           creating more drivers; programs need not be recompiled.
  77.         - Since the code to manage the specifics of each mode is
  78.           contained in the drivers, the main program needs not
  79.           concern itself with what mode it is operating in.  The
  80.           same code can work in any graphics mode.
  81.         - Memory is saved for programs which support many
  82.           graphics modes.  Instead of keeping the code and data
  83.           necessary for each in memory at all times, only the
  84.           memory required for one driver is used.
  85.  
  86.      When writing drivers, it is not necessary to write assembly
  87.      code for every graphical function that TGE supports.  For
  88.      instance, if a certain driver does not contain a line-
  89.      drawing routine, TGE will use its own.  Therefore, the
  90.      programmer needs not waste time writing assembly code which
  91.      will seldom or never be used, thus slashing development
  92.      time.  Essentially, no matter what a particular driver
  93.      contains, the entire set of TGE's graphical functions will
  94.      be available.
  95.  
  96.      In addition to essential graphical functions, TGE also
  97.      includes interrupt-driven definable mouse pointer services,
  98.      as well as a large number of functions to interface with the
  99.      mouse driver.
  100.  
  101.      The names of the graphical functions, such as "putImage" and
  102.      "filledRect" may easily be changed to suit individual
  103.      preferences.
  104.  
  105.      It's powerful, fast, and cheap.
  106.  
  107.  
  108.  
  109. SYSTEM REQUIREMENTS
  110. ───────────────────
  111.  
  112.      TGE is a C/C++ programmer's library.  As such, it requires a
  113.      C or C++ compiler of some sort to work with it.  TGE was
  114.      written and tested with Borland C++ 2.0 and Turbo C 2.0, and
  115.      also tested with Mix Power C 2.1.2.  It should work with
  116.      other C/C++ compilers as well.
  117.  
  118.      The drivers that come with TGE are written using 80286
  119.      instructions.  They therefore cannot be used on a processor
  120.      older than the 286 unless they are modified first.
  121.      The loadable drivers are written in assembly language.  In
  122.      order to write drivers, an assembler will be required.
  123.  
  124.      The font code is C++, not C. In order to use loadable fonts,
  125.      a C++ compiler will be required.
  126.  
  127.  
  128.  
  129. PACKING LIST
  130. ────────────
  131.  
  132.      The current version of TGE consists of the following files:
  133.  
  134.      TGE.DOC             TGE documentation
  135.      TGEDEMO.EXE         TGE demo program
  136.      320X200.DRV         Driver for VGA 320x200x256
  137.      320X240.DRV         Driver for VGA 320x240x256
  138.      320X400.DRV         Driver for VGA 320x400x256
  139.      360X480.DRV         Driver for VGA 360x480x256
  140.      640X480.DRV         Driver for SuperVGA/VESA 640x480x256 
  141.      800X600.DRV         Driver for SuperVGA/VESA 800x600x256 
  142.      1024X768.DRV        Driver for SuperVGA/VESA 1024x768x256 
  143.      8X8.FNT             8x8 font definition file
  144.      8X14.FNT            8x14 font definition file
  145.      8X16.FNT            8x16 font definition file
  146.      PCX2RAW.ARJ         Image format translation utility and its
  147.                          source code
  148.           PCX2RAW.EXE    Executable version
  149.           PCX2RAW.CPP    Source for above
  150.           PCX.CPP        PCX routines
  151.           TYPES.H        Some handy typedefs
  152.      SOURCE.ARJ          Full source code
  153.           TGE.H          TGE header file
  154.           TGE.C          Main C file
  155.           CLIP.C         Supplementary clipping routines
  156.           TGEFONT.H      Header file for TGE fonts
  157.           TGEFONT.CPP    TGE font support (C++ only)
  158.           TGEMOUSE.H     Mouse header file
  159.           TGEMOUSE.ASM   Various mouse routines
  160.           MOUSEPTR.C     Definable mouse pointer support
  161.           NEWMOUSE.ASM   More definable pointer support
  162.           TGEDEMO.CPP    Source for TGEDEMO.EXE
  163.           320X200.ASM    320x200x256 source
  164.           320X240.ASM    320x240x256 source
  165.           320X400.ASM    320x400x256 source
  166.           360X480.ASM    360x480x256 source
  167.           640X480.ASM    640x480x256 source
  168.           800X600.ASM    800x600x256 source
  169.           1024X768.ASM   1024x768x256 source
  170.           SHELL.ASM      Skeleton driver source; use this file as
  171.                          a basis in making custom drivers
  172.           CDRV.BAT       Create a .DRV from .ASM
  173.      REGISTER.FRM        Registration form
  174.  
  175.  
  176.      If you did not receive all of these files, you have an
  177.      illegal copy of The Graphics Engine.
  178.  
  179.  
  180.  
  181. RELEASE NOTES FOR VERSION 1.20
  182. ──────────────────────────────
  183.  
  184.      TGE now supports loadable fonts, viewports, region fills,
  185.      and colour approximation.
  186.  
  187.      The loadGraphDriver() routine has been rewritten to provide
  188.      for more descriptive return values.  If this version of TGE
  189.      is to be used in a program built with a previous version, a
  190.      slight change to the code will be necessary when checking
  191.      whether or not loadGraphDriver() succeeded; see
  192.      INCORPORATING THE GRAPHICS ENGINE for details.  Similarly,
  193.      the syntax for initNewMouse() has changed; it now has no
  194.      parameters.  Other parts of the code have been touched up in
  195.      less important ways.
  196.  
  197.      This version fixes the Trident 8900 800x600 bug in release
  198.      1.10.
  199.  
  200.      TGE has not been tested with any compilers other than
  201.      Borland C++ 2.0, Turbo C 2.0, and Mix Power C 2.1.2. 
  202.      Although provisions have been made in the code which aid
  203.      portability, it may not work with other compilers in spite
  204.      of these efforts.
  205.  
  206.      The loadable drivers used with this release are not
  207.      compatible with the drivers from version 1.10 or older, due
  208.      to changes in the drivers.
  209.  
  210.  
  211.  
  212. INCORPORATING THE GRAPHICS ENGINE
  213. ─────────────────────────────────
  214.  
  215.      Incorporating TGE into a program is an easy process
  216.      involving four simple steps.
  217.  
  218.      First, the header file TGE.H must be #included into any
  219.      source file which accesses any of TGE's routines.  TGE.C
  220.      must be compiled and linked into the .EXE file.
  221.  
  222.      Second, a graphics driver MUST be loaded before any
  223.      graphical functions are accessed; results are undefined if
  224.      this step is not followed.  Code to load a driver might look
  225.      like this:
  226.           if (loadGraphDriver(drvFileName) != TGE_SUCCESS)
  227.           {
  228.             printf("Error loading \"%s\".\n\n", drvFileName);
  229.             exit(1);
  230.           }
  231.           else
  232.             atexit(unloadGraphDriver);
  233.      Obviously, the function loadGraphDriver() MUST be called. 
  234.      As its only parameter, it takes a string consisting of the
  235.      file name (which may include any valid DOS path) of the
  236.      driver to be loaded.  It returns a success code: 
  237.      TGE_SUCCESS if the loading was successful, or one of
  238.      TGE_OPEN_ERR (file not found), TGE_FORMAT_ERR (file is not a
  239.      TGE driver), TGE_ALLOC_ERR (out of memory), and TGE_FILE_ERR
  240.      (general file I/O error) if an error occurred.  These macros
  241.      are defined in TGE.H.
  242.  
  243.      Third, information about the graphics mode should be
  244.      obtained from the graphics driver.  The following code will
  245.      store the maximum X-coordinate, Y-coordinate, and colour
  246.      number in the variables maxx, maxy, and colours
  247.      respectively:
  248.           maxx = MAXX;                  // set up variables
  249.           maxy = MAXY;
  250.           maxColour = MAXCOLOUR;
  251.      This step is not necessary, but helps improve speed.  (MAXX,
  252.      MAXY, and MAXCOLOUR are macros which expand to references of
  253.      a structure via a pointer; global variables are much
  254.      faster.)
  255.  
  256.      Fourth, after TGE's graphical functions are no longer needed
  257.      (usually just before a program exit), the function
  258.      unloadGraphDriver() should be called.  It takes no
  259.      parameters, and returns nothing.  It simply frees the memory
  260.      taken up by a driver after it has been loaded.  (With some
  261.      compilers it is not necessary to call this function, but
  262.      it's safer to call it just to be sure.)  It is often a good
  263.      idea to place unloadGraphDriver() in the atexit() queue.
  264.  
  265.      Note that the initGraphics() function must be called to
  266.      enter graphics mode; for more information, see the next
  267.      section.
  268.  
  269.      Information on incorporating TGE's mouse routines may be
  270.      found in the section entitled USING THE MOUSE.
  271.  
  272.  
  273.  
  274. THE GRAPHICS ENGINE'S GRAPHICAL FUNCTION SET
  275. ────────────────────────────────────────────
  276.  
  277.      After a driver has been loaded, all of TGE's graphical
  278.      functions can be accessed.  To call a function, simply
  279.      execute
  280.           functionName(parameter list);
  281.      where "functionName" is the name of the desired function
  282.      (eg. "line" or "filledRect") and "parameter list" is all
  283.      parameters to that function, if any.
  284.  
  285.      A complete list of TGE's graphical functions follows.
  286.  
  287.  *** Function:      initGraphics()
  288.      Syntax:        void huge initGraphics(void);
  289.      Purpose:       Initialize graphics mode.
  290.      Parameters:    None.
  291.      Return value:  1 on success or 0 on error.
  292.      Remarks:       On any call other than its first,
  293.                     initGraphics will also restore the colour
  294.                     palette which was active at the time
  295.                     deInitGraphics() was last called.
  296.      See also:      deInitGraphics()
  297.  
  298.  *** Function:      deInitGraphics()
  299.      Syntax:        void deInitGraphics(void);
  300.      Purpose:       Revert to 80x25 colour text mode.
  301.      Parameters:    None.
  302.      Return value:  None.
  303.      Remarks:       deInitGraphics will keep a copy of the active
  304.                     colour palette before shutting off graphics. 
  305.                     This palette will be restored by any future
  306.                     call to initGraphics().
  307.      See also:      initGraphics()
  308.  
  309.  *** Function:      putImage()
  310.      Syntax:        void huge putImage(int x, int y, void far
  311.                     *image);
  312.      Purpose:       Place a bitmap, or image, onto the screen.
  313.      Parameters:    The bitmap contained in 'image' will be
  314.                     placed onto the screen with its upper-left
  315.                     coordinate at ('x','y').
  316.      Return value:  None.
  317.      Remarks:            Clipping is performed; the image may be
  318.                     placed entirely on-screen, partially on-
  319.                     screen, or entirely off-screen.
  320.                          This function is declared as huge so
  321.                     that it will work properly when called from
  322.                     within an interrupt service routine.
  323.      See also:      putImageInv(), getImage(), imageSize(),
  324.                     putLine(), getLine()
  325.  
  326.  *** Function:      putImageInv()
  327.      Syntax:        void huge putImageInv(int x, int y, void far
  328.                     *image);
  329.      Purpose:       Place a bitmap, or image, on the screen.
  330.      Parameters:    The bitmap contained in 'image' will be
  331.                     placed onto the screen with its upper-left
  332.                     coordinate at ('x','y').
  333.      Return value:  None.
  334.      Remarks:            Clipping is performed; the image may be
  335.                     placed entirely on-screen, partially on-
  336.                     screen, or entirely off-screen.    
  337.                     putImageInv() differs from putImage() only in
  338.                     that it allows for transparent, or invisible,
  339.                     colours.  If any pixel in the image buffer
  340.                     has a value of zero, the corresponding pixel
  341.                     on-screen will not be modified.  Using
  342.                     putImageInv() can avoid having black borders
  343.                     around non-rectangular shapes.
  344.                          This function is declared as huge so
  345.                     that it will work properly when called from
  346.                     within an interrupt service routine.
  347.      See also:      putImage(), getImage(), imageSize(),
  348.                     putLine(), getLine()
  349.  
  350.  *** Function:      getImage()
  351.      Syntax:        void huge getImage(int ulx, int uly, int lrx,
  352.                     int lry, void far *image);
  353.      Purpose:       Copy the specified rectangular portion of the
  354.                     screen to memory.
  355.      Parameters:    The portion of the screen with its upper-left
  356.                     coordinate at ('ulx','uly') and its lower-
  357.                     left coordinate at ('lrx','lry') will be
  358.                     copied into the previously allocated memory
  359.                     region at 'image' (see imageSize()).
  360.      Return value:  None.
  361.      Remarks:            Clipping is performed.  Note that only
  362.                     the portion of the specified region which
  363.                     lies within the current viewport will be
  364.                     placed in the image buffer by getImage().  Be
  365.                     careful not to assume that a getImage() image
  366.                     has off-screen data in it.
  367.                          This function is declared as huge so
  368.                     that it will work properly when called from
  369.                     within an interrupt service routine.
  370.      See also:      putImage(), putImageInv(), imageSize(),
  371.                     putLine(), getLine()
  372.  
  373.  *** Function:      imageSize()
  374.      Syntax:        unsigned long imageSize(int ulx, int uly, int
  375.                     lrx, int lry);
  376.      Purpose:       Determine the amount of memory required to
  377.                     hold a rectangular portion of the screen.
  378.      Parameters:    imageSize() will calculate the amount of
  379.                     memory required to hold the porion of the
  380.                     screen whose upper-left coordinate is
  381.                     ('ulx','uly') and whose lower-left coordinate
  382.                     is ('lrx','lry').
  383.      Return value:  imageSize returns an unsigned long containing
  384.                     the size of the area in bytes.
  385.      Remarks:            Clipping is performed.
  386.                          imageSize() is designed for use with
  387.                     putImage(), putImageInv(), and getImage(). 
  388.                     To use it with putLine() and getLine(),
  389.                     subtract 4 from the value it returns.  (Image
  390.                     buffers have four bytes of dimension
  391.                     information in them; line buffers do not.)
  392.      See also:      putImage(), putImageInv(), getImage(),
  393.                     putLine(), getLine()
  394.  
  395.  *** Function:      putLine()
  396.      Syntax:        void putLine(int lineNum, int xOff, int
  397.                     lineLen, void far *buf);
  398.      Purpose:       Place one horizontal line of image data on
  399.                     the screen.
  400.      Parameters:    The one-line bitmap contained in 'buf', of
  401.                     'lineLen' pixels, will be placed on-screen
  402.                     starting at ('xOff','lineNum').
  403.      Return value:  None.
  404.      Remarks:       No clipping is performed.  Results are
  405.                     undefined if any coordinate on the line is
  406.                     off-screen.
  407.      See also:      getLine(), putImage(), putImageInv(),
  408.                     getImage()
  409.  
  410.  *** Function:      getLine()
  411.      Syntax:        void getLine(int lineNum, int xOff, int
  412.                     lineLen, void far *buf);
  413.      Purpose:       Copy one horizontal line from the screen to
  414.                     memory.
  415.      Parameters:    The horizontal line whose left coordinate is
  416.                     ('xOff','lineNum') and whose length is
  417.                     'lineLen' pixels will be copied into the
  418.                     previously allocated memory region at 'buf'.
  419.      Return value:  None.
  420.      Remarks:       No clipping is performed.  Results are
  421.                     undefined if any coordinate on the line is
  422.                     off-screen.
  423.      See also:      putLine(), putImage(), putImageInv(),
  424.                     getImage()
  425.  
  426.  *** Function:      putPixel()
  427.      Syntax:        void putPixel(int x, int y, unsigned colour);
  428.      Purpose:       Place a single pixel on-screen.
  429.      Parameters:    The pixel located at ('x','y') will be set to
  430.                     the colour 'colour'.
  431.      Return value:  None.
  432.      Remarks:       Clipping is not performed; see clipPoint()
  433.                     and pointOnScreen() for details on clipping
  434.                     pixels.
  435.      See also:      getPixel()
  436.  
  437.  *** Function:      getPixel()
  438.      Syntax:        unsigned getPixel(int x, int y);
  439.      Purpose:       Return the value of a pixel.
  440.      Parameters:    The value of the pixel at ('x','y') is
  441.                     returned.
  442.      Return value:  The value of the pixel at (x,y) is returned.
  443.      Remarks:       Clipping is not performed; see clipPoint()
  444.                     and pointOnScreen() for details on clipping
  445.                     pixels.
  446.      See also:      putPixel()
  447.  
  448.  *** Function:      line()
  449.      Syntax:        void line(int x1, int y1, int x2, int y2,
  450.                     unsigned colour);
  451.      Purpose:       Draw a line between two points.
  452.      Parameters:    The line will be drawn joining ('x1','y1')
  453.                     and ('x2','y2') in the colour 'colour'.
  454.      Return value:  None.
  455.      Remarks:       Clipping is not performed; see clipLine() for
  456.                     details on clipping lines.
  457.      See also:      horizLine()
  458.  
  459.  *** Function:      horizLine()
  460.      Syntax:        void horizLine(int y, int x1, int x2,
  461.                     unsigned colour);
  462.      Purpose:       Draw a horizontal line between two points.
  463.      Parameters:    The line will be drawn between ('x1','y') and
  464.                     ('x2','y') in the colour contained in colour.
  465.      Return value:  None.
  466.      Remarks:       Clipping is not performed.
  467.      See also:      line()
  468.  
  469.  *** Function:      drawRect()
  470.      Syntax:        void drawRect(int ulx, int uly, int lrx, int
  471.                     lry, unsigned colour);
  472.      Purpose:       Draw a rectangle.
  473.      Parameters:    The rectangle will be drawn with its upper-
  474.                     left coordinates at ('ulx','uly') and its
  475.                     lower-left coordinates at ('lrx','lry'), in
  476.                     the colour 'colour'.
  477.      Return value:  None.
  478.      Remarks:       Clipping is performed.
  479.      See also:      filledRect()
  480.  
  481.  *** Function:      filledRect()
  482.      Syntax:        void filledRect(int ulx, int uly, int lrx,
  483.                     int lry, unsigned colour);
  484.      Purpose:       Draw a filled rectangle.
  485.      Parameters:    The rectangle will be drawn with its upper-
  486.                     left coordinates at ('ulx','uly') and its
  487.                     lower-left coordinates at ('lrx','lry'), in
  488.                     the colour 'colour'.
  489.      Return value:  None.
  490.      Remarks:       Clipping is not performed; see
  491.                     clipFilledRect() for details on clipping
  492.                     filledRects.
  493.      See also:      drawRect()
  494.  
  495.  *** Function:      setPaletteReg()
  496.      Syntax:        void setPaletteReg(unsigned palReg, unsigned
  497.                     char red, unsigned char green, unsigned char
  498.                     blue);
  499.      Purpose:       Set a palette register.
  500.      Parameters:    The red, green, and blue components of the
  501.                     palette register palReg will be set to 'red',
  502.                     'green', and 'blue' respectively.
  503.      Return value:  None.
  504.      Remarks:       Each of the colour components ('red',
  505.                     'green', 'blue') should be in the range
  506.                     0..255, not 0..63 as would be the case using
  507.                     a stock VGA.  The drivers will take care of
  508.                     converting 8-bit to 6-bit palette resolution
  509.                     if necessary.
  510.      See also:      getPaletteReg(), setBlockPalette(),
  511.                     getBlockPalette()
  512.  
  513.  *** Function:      getPaletteReg()
  514.      Syntax:        void getPaletteReg(unsigned palReg, unsigned
  515.                     char far *red, unsigned char far *green,
  516.                     unsigned char far *blue);
  517.      Purpose:       Return the current settings of a palette
  518.                     register.
  519.      Parameters:    The red, green, and blue contents of the
  520.                     palette register palReg will be stored in
  521.                     'red', 'green', and 'blue' respectively.
  522.      Return value:  The red, green, and blue components of the
  523.                     palette register are returned in 'red',
  524.                     'green', and 'blue'.
  525.      Remarks:       Each of the colour components ('red',
  526.                     'green', 'blue') are in the range 0..255, not
  527.                     0..63 as would be the case using a stock VGA. 
  528.                     The drivers will take care of converting 8-
  529.                     bit to 6-bit palette resolution if necessary.
  530.      See also:      setPaletteReg(), setBlockPalette(),
  531.                     getBlockPalette()
  532.  
  533.  *** Function:      setBlockPalette()
  534.      Syntax:        void setBlockPalette(unsigned firstReg,
  535.                     unsigned numRegs, void far *data);
  536.      Purpose:       Set a block of palette registers.
  537.      Parameters:    'numRegs' palette registers, starting at
  538.                     'firstReg', will be set to the values
  539.                     contained in 'data'.
  540.      Return value:  None.
  541.      Remarks:            The memory region at 'data' is organised
  542.                     in groups of three bytes; each group
  543.                     corresponds to one palette register, and each
  544.                     group is made up of, in order, the red,
  545.                     green, and blue components.  The first group
  546.                     is for the first register, the second for the
  547.                     second, and so on.
  548.                          Each of the colour components (red,
  549.                     green, blue) should be in the range 0..255,
  550.                     not 0..63 as would be the case using a stock
  551.                     VGA.  The drivers will take care of
  552.                     converting 8-bit to 6-bit palette resolution
  553.                     if necessary.
  554.      See also:      getBlockPalette(), setPaletteReg(),
  555.                     getPaletteReg()
  556.  
  557.  *** Function:      getBlockPalette()
  558.      Syntax:        void getBlockPalette(unsigned firstReg,
  559.                     unsigned numRegs, void far *data);
  560.      Purpose:       Get the values of a block of palette
  561.                     registers.
  562.      Parameters:    The values of 'numRegs' palette registers,
  563.                     starting at 'firstReg', will be stored in the
  564.                     previously allocated 'data'.
  565.      Return value:  The values are returned in 'data'.
  566.      Remarks:            The memory region at 'data' is organised
  567.                     in groups of three bytes; each group
  568.                     corresponds to one palette register, and each
  569.                     group is made up of, in order, the red,
  570.                     green, and blue components.  The first group
  571.                     is for the first register, the second for the
  572.                     second, and so on.
  573.                          Each of the colour components (red,
  574.                     green, blue) is in the range 0..255, not
  575.                     0..63 as would be the case using a stock VGA. 
  576.                     The drivers will take care of converting 8-
  577.                     bit to 6-bit palette resolution if necessary.
  578.      See also:      setBlockPalette(), setPaletteReg(),
  579.                     getPaletteReg()
  580.  
  581.  *** Function:      clearGraphics()
  582.      Syntax:        void clearGraphics(unsigned colour);
  583.      Purpose:       Clear the screen.
  584.      Parameters:    The screen will be cleared to the colour
  585.                     'colour'.
  586.      Return value:  None.
  587.      Remarks:       This function clears the entire screen, not
  588.                     just the current viewport.
  589.      See also:      filledRect()
  590.  
  591.  *** Function:      ellipse()
  592.      Syntax:        void ellipse(int x, int y, int wide, int
  593.                     deep, unsigned colour);
  594.      Purpose:       Draw the outline of an ellipse.
  595.      Parameters:    An ellipse centered at ('x','y') and having
  596.                     width 'wide' and depth 'deep' will be drawn
  597.                     in the colour 'colour'.
  598.      Return value:  None.
  599.      Remarks:       Clipping is performed.
  600.      See also:      filledEllipse(), circle(), filledCircle()
  601.  
  602.  *** Function:      filledEllipse()
  603.      Syntax:        void filledEllipse(x, int y, int wide, int
  604.                     deep, unsigned colour);
  605.      Purpose:       Draw a filled ellipse.
  606.      Parameters:    An ellipse centered at ('x','y') and having
  607.                     width 'wide' and depth 'deep' will be drawn
  608.                     in the colour 'colour'.
  609.      Return value:  None.
  610.      Remarks:       Clipping is performed.
  611.      See also:      ellipse(), filledCircle(), circle()
  612.  
  613.  *** Function:      circle()
  614.      Syntax:        void circle(int x, int y, int radius,
  615.                     unsigned colour);
  616.      Purpose:       Draw the outline of a circle.
  617.      Parameters:    A circle centered at ('x','y') and having
  618.                     radius 'radius' will be drawn in the colour
  619.                     'colour'.
  620.      Return value:  None.
  621.      Remarks:            Clipping is performed.
  622.                          The 'radius' parameter is the radius in
  623.                     pixels measured horizontally.  Although there
  624.                     will be no difference in modes with square
  625.                     pixels, it will make a difference in other
  626.                     modes; to ensure accurate drawing of the
  627.                     circle with the given radius, make certain
  628.                     that the radius is measured horizontally.
  629.                          TGE uses an all-integer approach to
  630.                     coordinate scaling to ensure that the drawn
  631.                     shape will be circular in modes without
  632.                     square pixels.
  633.      See also:      filledCircle(), filledEllipse(), ellipse()
  634.  
  635.  *** Function:      filledCircle()
  636.      Syntax:        void filledCircle(int x, int y, int radius,
  637.                     unsigned colour);
  638.      Purpose:       Draw a filled circle.
  639.      Parameters:    A circle centered at ('x','y') and having
  640.                     radius 'radius' will be drawn in the colour
  641.                     'colour'.
  642.      Return value:  None.
  643.      Remarks:            Clipping is performed.
  644.                          The 'radius' parameter is the radius in
  645.                     pixels measured horizontally.  Although there
  646.                     will be no difference in modes with square
  647.                     pixels, it will make a difference in other
  648.                     modes; to ensure accurate drawing of the
  649.                     circle with the given radius, make certain
  650.                     that the radius is measured horizontally.
  651.                          TGE uses an all-integer approach to
  652.                     coordinate scaling to ensure that the drawn
  653.                     shape will be circular in modes without
  654.                     square pixels.
  655.      See also:      circle(), ellipse(), filledEllipse()
  656.  
  657.  *** Function:      fillRegion()
  658.      Syntax:        void fillRegion(int x, int y, unsigned
  659.                     colour);
  660.      Purpose:       Floods a region of the screen with the
  661.                     specified colour.
  662.      Parameters:    The fill will begin at the seed point
  663.                     ('x','y'), and will fill with the colour
  664.                     'colour'.
  665.      Return value:  None.
  666.      Remarks:            The region to be filled is bounded by
  667.                     any colour not equal to the colour at
  668.                     ('x','y'); ie., the region to be filled
  669.                     consists of one colour only.
  670.                          Clipping is performed.
  671.      See also:      None.
  672.  
  673.  *** Function:      colourCloseTo()
  674.      Syntax:        unsigned colourCloseTo(unsigned char red,
  675.                     unsigned char green, unsigned char blue);
  676.      Purpose:       Given a 24-bit colour, find the colour from
  677.                     the current palette which most closely
  678.                     matches it.
  679.      Parameters:    The 24-bit colour is defined by the 'red',
  680.                     'green', and 'blue' parameters.
  681.      Return value:  Returns the colour which most closely matches
  682.                     the specified 24-bit colour.
  683.      Remarks:       None.
  684.      See also:      colourCloseToX()
  685.  
  686.  *** Function:      colourCloseToX()
  687.      Syntax:        unsigned colourCloseToX(unsigned char red,
  688.                     unsigned char green, unsigned char blue,
  689.                     unsigned colourExclude);
  690.      Purpose:       Given a 24-bit colour, find the colour from
  691.                     the current palette which most closely
  692.                     matches it, with the specified colour
  693.                     disallowed from the search.
  694.      Parameters:    The 24-bit colour is defined by the 'red',
  695.                     'green', and 'blue' parameters.  The colour
  696.                     'colourExclude' is excluded from the search,
  697.                     and so will never be returned.
  698.      Return value:  Returns the colour which most closely matches
  699.                     the specified 24-bit colour.
  700.      Remarks:       Excluding zero from a search will ensure that
  701.                     the returned colour will be visible when it
  702.                     is used as part of a bitmap displayed using
  703.                     putImageInv().
  704.      See also:      colourCloseTo()
  705.  
  706.  
  707.      Note that since these function names are actually macros,
  708.      they may easily be changed to suit individual preferences by
  709.      editing TGE.H.
  710.  
  711.  
  712.  
  713. VIEWPORTS AND CLIPPING
  714. ──────────────────────
  715.  
  716.      A viewport is a rectangular region on the screen to which
  717.      output is clipped.  By default, this region is the entire
  718.      screen; however, it can be set to any portion of the screen. 
  719.      (Note that when a viewport is in use, coordinates are
  720.      absolute, not relative to the viewport.)
  721.  
  722.      The following functions are used to get and set the current
  723.      viewport:
  724.  
  725.  *** Function:      setViewport()
  726.      Syntax:        void setViewport(int ulx, int uly, int lrx,
  727.                     int lry);
  728.      Purpose:       Set the defining coordinates of the current
  729.                     viewport.
  730.      Parameters:    The upper-left corner of the viewport will be
  731.                     set to ('ulx','uly'), and the lower-right
  732.                     corner to ('lrx','lry').
  733.      Return value:  None.
  734.      Remarks:       It is assumed that 'ulx'<'lrx' and that
  735.                     'uly'<'lry'.
  736.      See also:      getViewport()
  737.  
  738.  *** Function:      getViewport()
  739.      Syntax:        void getViewport(int far *ulx, int far *uly,
  740.                     int far *lrx, int far *lry);
  741.      Purpose:       Get the defining coordinates of the current
  742.                     viewport.
  743.      Parameters:    The upper-left corner of the viewport will be
  744.                     returned in ('ulx','uly'), and the lower-
  745.                     right corner in ('lrx','lry').
  746.      Return value:  None.
  747.      Remarks:       None.
  748.      See also:      setViewport()
  749.  
  750.  
  751.      Note, however, that not all of TGE's functions will clip to
  752.      within the current viewport.  Some of the time-critical
  753.      graphics primitives, such as putPixel() and line(), do not
  754.      clip in order to improve execution time.  If it is necessary
  755.      for such functions to have their output clipped, the
  756.      following routines may be used:
  757.  
  758.  *** Function:      clipFilledRect()
  759.      Syntax:        int clipFilledRect(int *x1, int *y1, int *x2,
  760.                     int *y2);
  761.      Purpose:       Clip the given filled rectangle to within the
  762.                     current viewport.
  763.      Parameters:    The upper-left and lower-right corners of the
  764.                     rectangle are passed in ('x1','y1') and
  765.                     ('x2','y2').  If clipping is done, these
  766.                     points will be modified.
  767.      Return value:  Returns true if the rectangle lies entirely
  768.                     or partially within the current viewport, or
  769.                     false if it is entirely outside the current
  770.                     viewport.
  771.      Remarks:            It does not matter which of the corner
  772.                     coordinates is passed first; they will be
  773.                     swapped if necessary.
  774.                          This function is contained in CLIP.C.
  775.  
  776.  *** Function:      clipLine()
  777.      Syntax:        int clipLine(int *x1, int *y1, int *x2, int
  778.                     *y2);
  779.      Purpose:       Clip the given line to within the current
  780.                     viewport.
  781.      Parameters:    The endpoints of the line are passed in
  782.                     ('x1','y1') and ('x2','y2').  If clipping is
  783.                     done, these endpoints will be modified.
  784.      Return value:  Returns true if the line lies entirely or
  785.                     partially within the current viewport, or
  786.                     false if it is entirely outside the current
  787.                     viewport.
  788.      Remarks:       This function is contained in CLIP.C.
  789.      See also:      None.
  790.  
  791.  *** Function:      clipPoint()
  792.      Syntax:        int clipPoint(int x, int y);
  793.      Purpose:       Return a flag indicating whether or not the
  794.                     specified coordinates lie within the current
  795.                     viewport.
  796.      Parameters:    The point ('x','y') is tested.
  797.      Return value:  Returns true if ('x','y') is within the
  798.                     current viewport, or 0 if it isn't.
  799.      Remarks:       This function is really a macro defined in
  800.                     TGE.H.
  801.      See also:      None.
  802.  
  803.  *** Function:      pointOnScreen()
  804.      Syntax:        int pointOnScreen(int x, int y);
  805.      Purpose:       Return a flag indicating whether or not the
  806.                     specified coordinates lie on-screen.
  807.      Parameters:    The point ('x','y') is tested.
  808.      Return value:  Returns true if ('x','y') is on-screen, or 0
  809.                     if it is off-screen.
  810.      Remarks:       This function is really a macro defined in
  811.                     TGE.H.
  812.      See also:      None.
  813.  
  814.  
  815.      Note that since these function names are actually macros,
  816.      they may easily be changed to suit individual preferences by
  817.      editing TGE.H.
  818.  
  819.  
  820.  
  821. FONTS
  822. ─────
  823.  
  824.      TGE supports loadable fonts, implemented in C++ using the
  825.      "Font" class.  At present, TGE's fonts are composed of
  826.      monochrome bitmaps of a single size, using one bitmap for
  827.      each character.  Both high- and low-ASCII characters are
  828.      supported.  As well, multiple fonts may be resident in
  829.      memory simultaneously.
  830.  
  831.      In order to use a font, an instance of the Font class is
  832.      necessary.  Assuming instantiation of a Font pointer, font
  833.      initialization will look something like this:
  834.  
  835.  
  836.           Font *systemFont;
  837.           char systemFontName[] = "8x16.fnt";
  838.  
  839.           .
  840.           .
  841.           .
  842.  
  843.           systemFont = new Font(systemFontName); // load font
  844.           if (!systemFont || !systemFont->status())
  845.           {
  846.             printf("Error loading %s\n\n", systemFontName);
  847.             exit(1);
  848.           }
  849.  
  850.  
  851.      Once a font has been loaded, it may be manipulated via its
  852.      Font class instance.  A complete list of the Font member
  853.      functions follows.
  854.  
  855.  
  856.  *** Function:      Font::Font()
  857.      Syntax:        Font::Font(char *filename, unsigned char
  858.                     fg=1, unsigned char bg=0);
  859.      Purpose:       Load a font, and initiate a Font class for
  860.                     use with it.
  861.      Parameters:    'filename' is the name of the font data file. 
  862.                     'fg' (optional) is the colour to be used as
  863.                     the foreground colour.  'bg' (optional) is
  864.                     the colour to be used as the background
  865.                     colour.
  866.      Return value:  None.
  867.      Remarks:       After an instantiation of a Font, ensure that
  868.                     the loading and initialization was successful
  869.                     using the method illustrated above.
  870.      See also:      Font::~Font()
  871.  
  872.  *** Function:      Font::~Font()
  873.      Syntax:        Font::~Font()
  874.      Purpose:       Free the memory used by a font, and perform
  875.                     any other clean-up actions when a Font is no
  876.                     longer needed.
  877.      Parameters:    None.
  878.      Return value:  None.
  879.      Remarks:       None.
  880.      See also:      Font::Font()
  881.  
  882.  *** Function:      Font::status()
  883.      Syntax:        inline int Font::status(void);
  884.      Purpose:       Return a flag indicating whether or not the
  885.                     font loading and initialization were
  886.                     successful.
  887.      Parameters:    None.
  888.      Return value:  Returns 1 if the initialization was
  889.                     successful, or 0 if it wasn't.
  890.      Remarks:       None.
  891.      See also:      None.
  892.  
  893.  *** Function:      Font::wide(char*)
  894.      Syntax:        unsigned Font::wide(char *str);
  895.      Purpose:       Return the width, in pixels, of a string.
  896.      Parameters:    The string 'str' is analyzed.
  897.      Return value:  Returns the width of 'str', in pixels.
  898.      Remarks:       None.
  899.      See also:      Font::wide(char), Font::deep(char*),
  900.                     Font::deep(char), Font::maxWide(),
  901.                     Font::maxDeep()
  902.  
  903.  *** Function:      Font::wide(char)
  904.      Syntax:        inline unsigned Font::wide(char ch);
  905.      Purpose:       Return the width, in pixels, of a single
  906.                     character.
  907.      Parameters:    The character 'ch' is analyzed.
  908.      Return value:  Returns the width of 'ch', in pixels.
  909.      Remarks:       None.
  910.      See also:      Font::wide(char*), Font::deep(char),
  911.                     Font::deep(char*), Font::maxWide(),
  912.                     Font::maxDeep()
  913.  
  914.  *** Function:      Font::maxWide(void)
  915.      Syntax:        inline unsigned maxWide(void);
  916.      Purpose:       Return the width of the widest character.
  917.      Parameters:    None.
  918.      Return value:  Returns the width of the widest character.
  919.      Remarks:       None.
  920.      See also:      Font::maxDeep(void), Font::wide(char*),
  921.                     Font::wide(char), Font::deep(char*),
  922.                     Font::deep(char)
  923.      
  924.  *** Function:      Font::deep(char*)
  925.      Syntax:        unsigned Font::deep(char *str);
  926.      Purpose:       Return the depth, in pixels, of a string.
  927.      Parameters:    The string 'str' is analyzed.
  928.      Return value:  Returns the depth of 'str', in pixels.
  929.      Remarks:       None.
  930.      See also:      Font::deep(char), Font::wide(char*),
  931.                     Font::deep(char), Font::maxDeep(),
  932.                     Font::maxWide()
  933.  
  934.  *** Function:      Font::deep(char)
  935.      Syntax:        unsigned Font::deep(char ch);
  936.      Purpose:       Return the depth, in pixels, of a single
  937.                     character.
  938.      Parameters:    The character 'ch' is analyzed.
  939.      Return value:  Returns the depth of 'ch', in pixels.
  940.      Remarks:       None.
  941.      See also:      Font::deep(char*), Font::wide(char),
  942.                     Font::wide(char*), Font::maxWide(),
  943.                     Font::maxDeep()
  944.  
  945.  *** Function:      Font::maxDeep(void)
  946.      Syntax:        inline unsigned maxDeep(void);
  947.      Purpose:       Return the depth of the deepest character.
  948.      Parameters:    None.
  949.      Return value:  Returns the depth of the deepest character.
  950.      Remarks:       None.
  951.      See also:      Font::maxWide(void), Font::deep(char*),
  952.                     Font::deep(char), Font::wide(char*),
  953.                     Font::wide(char)
  954.  
  955.  *** Function:      Font::put(int, int, char*)
  956.      Syntax:        void Font::put(int x, int y, char *str);
  957.      Purpose:       Write a string to the screen.
  958.      Parameters:    The string 'str' will be written starting at
  959.                     ('x','y').
  960.      Return value:  None.
  961.      Remarks:       The coordinate passed to this function
  962.                     specifies the upper-left coordinate of the
  963.                     string.
  964.      See also:      Font::put(char);
  965.      
  966.  *** Function:      Font::put(int, int, char)
  967.      Syntax:        void Font::put(int x, int y, char ch);
  968.      Purpose:       Write a single character to the screen.
  969.      Parameters:    The character 'ch' will be written at
  970.                     ('x','y').
  971.      Return value:  None.
  972.      Remarks:       The coordinate passed to this function
  973.                     specifies the upper-left coordinate of the
  974.                     character.
  975.      See also:      Font::put(char*);
  976.  
  977.  *** Function:      Font::foreground(unsigned)
  978.      Syntax:        inline void Font::foreground(unsigned
  979.                     colour);
  980.      Purpose:       Set the current foreground colour.
  981.      Parameters:    The foreground colour will be set to
  982.                     'colour'.
  983.      Return value:  None.
  984.      Remarks:       None.
  985.      See also:      Font::background(unsigned),
  986.                     Font::foreground(void),
  987.                     Font::background(void)
  988.  
  989.  *** Function:      Font::foreground(void)
  990.      Syntax:        inline unsigned Font::foreground(void);
  991.      Purpose:       Return the current foreground colour.
  992.      Parameters:    None.
  993.      Return value:  Returns the current foreground colour.
  994.      Remarks:       None.
  995.      See also:      Font::background(void),
  996.                     Font::foreground(unsigned),
  997.                     Font::foreground(unsigned)
  998.  
  999.  *** Function:      Font::background(unsigned)
  1000.      Syntax:        inline void Font::background(unsigned
  1001.                     colour);
  1002.      Purpose:       Set the current background colour.
  1003.      Parameters:    The background colour will be set to
  1004.                     'colour'.
  1005.      Return value:  None.
  1006.      Remarks:       None.
  1007.      See also:      Font::foreground(unsigned),
  1008.                     Font::background(void),
  1009.                     Font::foreground(void)
  1010.  
  1011.  *** Function:      Font::background(void)
  1012.      Syntax:        inline unsigned Font::background(void);
  1013.      Purpose:       Return the current background colour.
  1014.      Parameters:    None.
  1015.      Return value:  Returns the current background colour.
  1016.      Remarks:       None.
  1017.      See also:      Font::foreground(void),
  1018.                     Font::background(unsigned),
  1019.                     Font::foreground(unsigned)
  1020.  
  1021.  
  1022.      Note that, at present, TGE's fonts are designed for use in
  1023.      256-colour modes only.
  1024.  
  1025.  
  1026.  
  1027. USING THE MOUSE
  1028. ───────────────
  1029.  
  1030.      TGE now provides support for interrupt-driven, definable
  1031.      mouse pointers.  In order to make use of this feature, some
  1032.      simple steps must be taken.
  1033.  
  1034.      First, please be aware that the file MOUSEPTR.C is currently
  1035.      designed specifically for 256-colour modes.  This file is
  1036.      the one that creates the pointer bitmaps and passes them to
  1037.      the mouse driver; some modifications may be necessary in
  1038.      order for it to work in modes with other than 256 colours.
  1039.  
  1040.      The new mouse handler is designed to work in tandem with
  1041.      TGE's graphical functions.  Programs using the new mouse
  1042.      handler must first have successfully initialized graphics
  1043.      mode using TGE.  Both TGE.H and TGEMOUSE.H must be #included
  1044.      into a program using the mouse services.
  1045.  
  1046.      The mouse handler has to be initialized.  To do so, one
  1047.      function call is required:
  1048.           initNewMouse();
  1049.      For more information on initNewMouse(), refer to the mouse
  1050.      functions reference section.
  1051.  
  1052.      Next, the mouse driver must be informed of the screen
  1053.      dimensions, like this:
  1054.           setHorizLimitsMouse(0, maxx);
  1055.           setVertLimitsMouse(0, maxy);
  1056.      If desired, the pointer may then be positioned.  To center
  1057.      it on the screen, do this:
  1058.           setPosMouse((maxx+1)/2, (maxy+1)/2);
  1059.  
  1060.      A pointer shape must then be selected.  TGE, as shipped,
  1061.      includes an arrow pointer and a target pointer; the file
  1062.      MOUSEPTR.C may easily be modified to allow more.  To select,
  1063.      for instance, the target pointer, do this:
  1064.           setupMousePointer(TARGET_POINTER);
  1065.      The macro TARGET_POINTER is defined in TGEMOUSE.H; it
  1066.      expands to a number which is used by MOUSEPTR.C to identify
  1067.      which bitmap to use.  Note that if exceptionally large (ie.
  1068.      larger than 1 K) pointers are used, a change must be made in
  1069.      NEWMOUSE.ASM; see that file for details.
  1070.  
  1071.      Once things have been initialized, the use of the new mouse
  1072.      handler over the default driver can essentially be ignored;
  1073.      mouse driver services are obtained in exactly the same way. 
  1074.      The file TGEMOUSE.ASM contains functions to interface to
  1075.      most of the mouse driver's services; they are prototyped in
  1076.      TGEMOUSE.H, also using the macro method which allows
  1077.      function names to be changed simply by editing TGEMOUSE.H.
  1078.  
  1079.      Before exiting the program, the function deInitNewMouse()
  1080.      _must_ be called.  It is often a good idea to place
  1081.      deInitNewMouse() in the atexit() queue.
  1082.  
  1083.      Note that, since the pointer is drawn using TGE's
  1084.      putImageInv() function, the pointer will only appear when it
  1085.      is within the current viewport.
  1086.  
  1087.  
  1088.  
  1089. THE GRAPHICS ENGINE'S MOUSE FUNCTION SET
  1090. ────────────────────────────────────────
  1091.  
  1092.  *** Function:      initNewMouse()
  1093.      Purpose:       Initializes the new mouse handler.
  1094.      Parameters:    The new mouse handler will be configured for
  1095.                     use with TGE.
  1096.      Return value:  None.
  1097.      Remarks:            A graphics driver must have been loaded
  1098.                     prior to a call to initNewMouse().
  1099.                          The new mouse handler requires that a
  1100.                     Microsoft or compatible mouse driver already
  1101.                     be resident.  It assumes that a mouse
  1102.                     driver's presence will have been tested
  1103.                     beforehand.
  1104.                          initNewMouse() is really a simple macro;
  1105.                     refer to TGEMOUSE.H for the expansion.
  1106.      See also:      deInitNewMouse(), enableNewMouse(),
  1107.                     disableNewMouse(), resetMouse()
  1108.  
  1109.  *** Function:      deInitNewMouse()
  1110.      Syntax:        void deInitNewMouse(void);
  1111.      Purpose:       Deactivate the new mouse handler, and leave
  1112.                     all the work up to the old driver.
  1113.      Parameters:    None.
  1114.      Return value:  None.
  1115.      Remarks:       This function _must_ be called prior to
  1116.                     program exit if initNewMouse() had previously
  1117.                     been called.
  1118.      See also:      initNewMouse(), enableNewMouse(),
  1119.                     disableNewMouse()
  1120.  
  1121.  *** Function:      enableNewMouse()
  1122.      Syntax:        void enableNewMouse(void);
  1123.      Purpose:       Reactivate the new mouse handler following a
  1124.                     call to disableNewMouse().
  1125.      Parameters:    None.
  1126.      Return value:  None.
  1127.      Remarks:       None.
  1128.      See also:      disableNewMouse(), initNewMouse(),
  1129.                     deInitNewMouse()
  1130.  
  1131.  *** Function:      disableNewMouse()
  1132.      Syntax:        void disableNewMouse(void);
  1133.      Purpose:       Temporarily deactivate the new mouse handler,
  1134.                     to be reactivated later by a call to
  1135.                     enableNewMouse().
  1136.      Parameters:    None.
  1137.      Return value:  None.
  1138.      Remarks:       Following a call to this function, the new
  1139.                     mouse handler will cease trapping mouse
  1140.                     driver interrupts and moving the pointer.
  1141.      See also:      enableNewMouse(), initNewMouse(),
  1142.                     deInitNewMouse()
  1143.  
  1144.  *** Function:      resetMouse()
  1145.      Syntax:        int resetMouse(void);
  1146.      Purpose:       Reset the mouse driver and hardware.
  1147.      Parameters:    None.
  1148.      Return value:  1 if mouse driver available, 0 otherwise.
  1149.      Remarks:       Following a call to this function, the mouse
  1150.                     pointer is hidden and positioned at the
  1151.                     center of the screen.
  1152.      See also:      softResetMouse(), initNewMouse()
  1153.  
  1154.  *** Function:      getButtonsMouse()
  1155.      Syntax:        int getButtonsMouse(void);
  1156.      Purpose:       Return the number of buttons on the mouse.
  1157.      Parameters:    None.
  1158.      Return value:  Returns the number of buttons on the mouse.
  1159.      Remarks:       This function calls resetMouse(), and so the
  1160.                     mouse driver and hardware are re-initialized.
  1161.      See also:      resetMouse()
  1162.  
  1163.  *** Function:      showMouse()
  1164.      Syntax:        void showMouse(void);
  1165.      Purpose:       Show the mouse pointer.
  1166.      Parameters:    None.
  1167.      Return value:  None.
  1168.      Remarks:       Calls to showMouse() and hideMouse() are
  1169.                     cumulative; ie., if showMouse() is called
  1170.                     twice, hideMouse() must be called twice to
  1171.                     hide the pointer again.
  1172.      See also:      hideMouse()
  1173.  
  1174.  *** Function:      hideMouse()
  1175.      Syntax:        void hideMouse(void);
  1176.      Purpose:       Hide the mouse pointer.
  1177.      Parameters:    None.
  1178.      Return value:  None.
  1179.      Remarks:       Calls to showMouse() and hideMouse() are
  1180.                     cumulative; ie., if showMouse() is called
  1181.                     twice, hideMouse() must be called twice to
  1182.                     hide the pointer again.
  1183.      See also:      showMouse()
  1184.  
  1185.  *** Function:      getPosMouse()
  1186.      Syntax:        void getPosMouse(int far *x, int far *y);
  1187.      Purpose:       Get the current pointer coordinates.
  1188.      Parameters:    The current pointer x- and y-coordinates will
  1189.                     be stored in 'x' and 'y', respectively.
  1190.      Return value:  None.
  1191.      Remarks:       None.
  1192.      See also:      setPosMouse()
  1193.  
  1194.  *** Function:      setPosMouse()
  1195.      Syntax:        void setPosMouse(unsigned x, unsigned y);
  1196.      Purpose:       Set the current pointer coordinates.
  1197.      Parameters:    The pointer will be positioned at ('x','y').
  1198.      Return value:  None.
  1199.      Remarks:       None.
  1200.      See also:      getPosMouse()
  1201.  
  1202.  *** Function:      buttonMouse()
  1203.      Syntax:        int buttonMouse(void);
  1204.      Purpose:       Return whether or not any of the mouse
  1205.                     buttons is down.
  1206.      Parameters:    None.
  1207.      Return value:  Returns true if at least one button is down,
  1208.                     or zero if none of them is down.
  1209.      Remarks:       None.
  1210.      See also:      leftButtonMouse(), rightButtonMouse(),
  1211.                     centerButtonMouse(), waitReleaseMouse()
  1212.  
  1213.  *** Function:      leftButtonMouse()
  1214.      Syntax:        int leftButtonMouse(void);
  1215.      Purpose:       Return the status of the left mouse button.
  1216.      Parameters:    None.
  1217.      Return value:  Returns true if the button is down, or zero
  1218.                     if it is up.
  1219.      Remarks:       None.
  1220.      See also:      buttonMouse(), rightButtonMouse(),
  1221.                     centerButtonMouse(), waitReleaseMouse()
  1222.  
  1223.  *** Function:      rightButtonMouse()
  1224.      Syntax:        int rightButtonMouse(void);
  1225.      Purpose:       Return the status of the right mouse button.
  1226.      Parameters:    None.
  1227.      Return value:  Returns true if the button is down, or zero
  1228.                     if it is up.
  1229.      Remarks:       None.
  1230.      See also:      buttonMouse(), leftButtonMouse(),
  1231.                     centerButtonMouse(), waitReleaseMouse()
  1232.  
  1233.  *** Function:      centerButtonMouse()
  1234.      Syntax:        int centerButtonMouse(void);
  1235.      Purpose:       Return the status of the center mouse button.
  1236.      Parameters:    None.
  1237.      Return value:  Returns true if the button is down, or zero
  1238.                     if it is up.
  1239.      Remarks:       None.
  1240.      See also:      buttonMouse(), leftButtonMouse(),
  1241.                     rightButtonMouse(), waitReleaseMouse()
  1242.  
  1243.  *** Function:      buttonPressMouse()
  1244.      Syntax:        unsigned buttonPressMouse(unsigned button,
  1245.                     int far *x, int far *y);
  1246.      Purpose:       Return the number of times the specified
  1247.                     button has been pressed since the last call
  1248.                     to this function (with the same button
  1249.                     parameter), and store the coordinates of the
  1250.                     last press.
  1251.      Parameters:    The button 'button' is checked, and may be
  1252.                     any of LEFTBUTTON, RIGHTBUTTON, and
  1253.                     CENTERBUTTON, which are defined in
  1254.                     TGEMOUSE.H.  The position of the last press
  1255.                     will be stored in ('x','y').
  1256.      Return value:  Returns the number of times the specified
  1257.                     button has been pressed since the last call
  1258.                     to this function (with the same button
  1259.                     parameter).
  1260.      Remarks:       None.
  1261.      See also:      buttonReleaseMouse()
  1262.  
  1263.  *** Function:      buttonReleaseMouse()
  1264.      Syntax:        unsigned buttonReleaseMouse(unsigned button,
  1265.                     int far *x, int far *y);
  1266.      Purpose:       Return the number of times the specified
  1267.                     button has been released since the last call
  1268.                     to this function (with the same button
  1269.                     parameter), and store the coordinates of the
  1270.                     last press.
  1271.      Parameters:    The button 'button' is checked, and may be
  1272.                     any of LEFTBUTTON, RIGHTBUTTON, and
  1273.                     CENTERBUTTON, which are defined in
  1274.                     TGEMOUSE.H.  The position of the last release
  1275.                     will be stored in ('x','y').
  1276.      Return value:  Returns the number of times the specified
  1277.                     button has been released since the last call
  1278.                     to this function (with the same button
  1279.                     parameter).
  1280.      Remarks:       None.
  1281.      See also:      buttonPressMouse()
  1282.  
  1283.  *** Function:      setHorizLimitsMouse()
  1284.      Syntax:        void setHorizLimitsMouse(unsigned min,
  1285.                     unsigned max);
  1286.      Purpose:       Set the minimum and maximum horizontal
  1287.                     coordinates for the pointer.
  1288.      Parameters:    The minimum horizontal coordinate will be set
  1289.                     to 'min', and the maximum to 'max'.
  1290.      Return value:  None.
  1291.      Remarks:       None.
  1292.      See also:      setVertLimitsMouse()
  1293.  
  1294.  *** Function:      setVertLimitsMouse()
  1295.      Syntax:        void setVertLimitsMouse(unsigned min,
  1296.                     unsigned max);
  1297.      Purpose:       Set the minimum and maximum vertical
  1298.                     coordinates for the pointer.
  1299.      Parameters:    The minimum vertical coordinate will be set
  1300.                     to 'min', and the maximum to 'max'.
  1301.      Return value:  None.
  1302.      Remarks:       None.
  1303.      See also:      setHorizLimitsMouse()
  1304.  
  1305.  *** Function:      setPointerMouse()
  1306.      Syntax:        void setPointerMouse(int xOff, int yOff, void
  1307.                     far *p);
  1308.      Purpose:       Set the shape of the pointer.
  1309.      Parameters:    The image pointed to by 'p' will be the
  1310.                     pointer bitmap.  ('xOff','yOff') is the
  1311.                     offset, relative to the upper-left corner of
  1312.                     the bitmap, of the "hot spot" -- the pixel
  1313.                     where the pointer is actually registered as
  1314.                     being.  (For instance, the standard arrow
  1315.                     pointer has its hot spot in the upper-left,
  1316.                     while a crosshairs pointer would have it
  1317.                     towards the middle.)
  1318.      Return value:  None.
  1319.      Remarks:       None.
  1320.      See also:      None.
  1321.  
  1322.  *** Function:      getSaveSizeMouse()
  1323.      Syntax:        unsigned getSaveSizeMouse(void);
  1324.      Purpose:       Return the size of the buffer necessary to
  1325.                     store the state of the mouse driver.
  1326.      Parameters:    None.
  1327.      Return value:  Returns the size of the buffer.
  1328.      Remarks:       If a program using TGE and the new mouse
  1329.                     handling routines is to run another program,
  1330.                     for instance shelling to DOS, the ensuing
  1331.                     procedure should be followed:  call
  1332.                     disableNewMouse(), call getSaveSizeMouse(),
  1333.                     allocate a block of memory with the size
  1334.                     returned by getSaveSizeMouse(), call
  1335.                     saveStateMouse(), run the program, call
  1336.                     restoreStateMouse(), free the block of
  1337.                     memory, then call enableNewMouse().
  1338.      See also:      saveStateMouse(), restoreStateMouse()
  1339.  
  1340.  *** Function:      saveStateMouse()
  1341.      Syntax:        void saveStateMouse(void far *buf);
  1342.      Purpose:       Save the current state of the mouse driver.
  1343.      Parameters:    The block of memory pointed to by 'buf' will
  1344.                     be used to store the state data.  Its length
  1345.                     should be obtained by calling
  1346.                     getSaveSizeMouse().
  1347.      Return value:  None.
  1348.      Remarks:       If a program using TGE and the new mouse
  1349.                     handling routines is to run another program,
  1350.                     for instance shelling to DOS, the ensuing
  1351.                     procedure should be followed:  call
  1352.                     disableNewMouse(), call getSaveSizeMouse(),
  1353.                     allocate a block of memory with the size
  1354.                     returned by getSaveSizeMouse(), call
  1355.                     saveStateMouse(), run the program, call
  1356.                     restoreStateMouse(), free the block of
  1357.                     memory, then call enableNewMouse().
  1358.      See also:      getSaveSizeMouse(), restoreStateMouse()
  1359.  
  1360.  *** Function:      restoreStateMouse()
  1361.      Syntax:        void restoreStateMouse(void far *buf);
  1362.      Purpose:       Restore the state of the mouse driver from a
  1363.                     buffer previously filled by saveStateMouse().
  1364.      Parameters:    The block of memory pointed to by 'buf'
  1365.                     stores the state data.
  1366.      Return value:  None.
  1367.      Remarks:       If a program using TGE and the new mouse
  1368.                     handling routines is to run another program,
  1369.                     for instance shelling to DOS, the ensuing
  1370.                     procedure should be followed:  call
  1371.                     disableNewMouse(), call getSaveSizeMouse(),
  1372.                     allocate a block of memory with the size
  1373.                     returned by getSaveSizeMouse(), call
  1374.                     saveStateMouse(), run the program, call
  1375.                     restoreStateMouse(), free the block of
  1376.                     memory, then call enableNewMouse().
  1377.      See also:      getSaveSizeMouse, saveStateMouse
  1378.  
  1379.  *** Function:      setRatioMouse()
  1380.      Syntax:        void setRatioMouse(unsigned horiz, unsigned
  1381.                     vert);
  1382.      Purpose:       Set the mouse sensitivity, in units of
  1383.                     mickeys per 8 pixels of pointer movement.  (A
  1384.                     mickey is the unit used to measure mouse
  1385.                     movement.)
  1386.      Parameters:    The horizontal mickeys to pixels ratio will
  1387.                     be set to 'horiz', and the vertical to
  1388.                     'vert'.
  1389.      Return value:  None.
  1390.      Remarks:       None.
  1391.      See also:      getSensitivityMouse()
  1392.  
  1393.  *** Function:      getSensitivityMouse()
  1394.      Syntax:        void getSensitivityMouse(unsigned *horiz,
  1395.                     unsigned *vert, unsigned *doubleSpeed);
  1396.      Purpose:       Get the mouse sensitivity, in units of
  1397.                     mickeys per 8 pixels of pointer movement.  (A
  1398.                     mickey is the unit used to measure mouse
  1399.                     movement.)  The mouse double speed threshold
  1400.                     (the minimum number of mickeys per second of
  1401.                     motion before pointer movement is doubled) is
  1402.                     retrieved as well.
  1403.      Parameters:    The horizontal mickeys to pixels ratio will
  1404.                     be stored in 'horiz', the vertical in 'vert',
  1405.                     and the double speed threshold in
  1406.                     'doubleSpeed'.
  1407.      Return value:  None.
  1408.      Remarks:       None.
  1409.      See also:      setRatioMouse()
  1410.  
  1411.  *** Function:      softResetMouse()
  1412.      Syntax:        void softResetMouse(void);
  1413.      Purpose:       Reset the mouse driver, but not the hardware.
  1414.      Parameters:    None.
  1415.      Return value:  None.
  1416.      Remarks:       This function is equivalent to resetMouse(),
  1417.                     except in that it performs no initialization
  1418.                     of the mouse hardware.
  1419.      See also:      resetMouse()
  1420.  
  1421.  *** Function:      waitReleaseMouse()
  1422.      Syntax:        void waitReleaseMouse(int button);
  1423.      Purpose:       If the specified button is not already up,
  1424.                     wait until it is released, then return.
  1425.      Parameters:    The button 'button' is checked, and may be
  1426.                     any of LEFTBUTTON, RIGHTBUTTON, and
  1427.                     CENTERBUTTON, which are defined in
  1428.                     TGEMOUSE.H.
  1429.      Return value:  None.
  1430.      Remarks:       None.
  1431.      See also:      buttonMouse(), leftButtonMouse(),
  1432.                     rightButtonMouse(), centerButtonMouse()
  1433.  
  1434.  
  1435.      Note that since these function names are actually macros,
  1436.      they may easily be changed to suit individual preferences by
  1437.      editing TGEMOUSE.H.
  1438.  
  1439.  
  1440.  
  1441. WRITING GRAPHICS DRIVERS
  1442. ────────────────────────
  1443.  
  1444.      To build a new graphics driver, follow these steps:
  1445.  
  1446.      1.  Copy the file SHELL.ASM to another file, for example,
  1447.      MYDRV.ASM.
  1448.  
  1449.      2.  Change the maximum X-coordinate, Y-coordinate, and
  1450.      colour number to the appropriate values.  (They are clearly
  1451.      identified with comments.)  Also change the aspect ratio
  1452.      values to the correct values.  For example, in 800x600
  1453.      resolution, the x:y ratio is 800:600, which simplifies to
  1454.      4:3 in lowest terms when both sides are divided by 200.  In
  1455.      this case, the first of the two numbers in the driver will
  1456.      be 4, and the second will be 3.
  1457.  
  1458.      3.  A graphics driver must always contain the initGraphics()
  1459.      routine.  Replace the default one from SHELL.ASM with
  1460.      whatever the appropriate code is.  (Be sure to add return
  1461.      value logic, described in the initGraphics() description
  1462.      above.)
  1463.  
  1464.      4.  If the new video mode is not supported by the video
  1465.      BIOS, custom putPixel() and getPixel() routines must be
  1466.      written and placed in the driver.  Doing so is advised
  1467.      anyway, as the BIOS is notoriously slow.
  1468.  
  1469.      5.  The default palette management routines assume that the
  1470.      video mode's palette registers have a resolution of six
  1471.      bits.  The standard VGA has only 6-bit resolution, but some
  1472.      SuperVGAs support 8-bit resolution.  If the video mode for
  1473.      which the driver is being written supports a true 8-bit
  1474.      palette, the four palette management routines should be
  1475.      written and placed in the driver.
  1476.  
  1477.      6.  Several routines assume that each pixel has a size of
  1478.      exactly one byte, as 256-colour modes are so common. 
  1479.      (Namely, these routines are putImage(), getImage(),
  1480.      putLine(), getLine(), imageSize(), putPixel(), and
  1481.      getPixel().)  If the new video mode does not have one-byte
  1482.      pixels, these routines should be written and placed in the
  1483.      driver.
  1484.  
  1485.      7.  If the new video mode is not a 256-colour mode, the
  1486.      colourCloseTo() and colourCloseToX() functions should be
  1487.      written and placed in the driver.
  1488.  
  1489.      8.  If speed is important, write any routines that have not
  1490.      already been written.
  1491.  
  1492.      9.  For every routine that has been written, a change must
  1493.      be made in the header of the driver's source code so that
  1494.      loadGraphDriver() recognize it.  As an example, assume that
  1495.      horizLine has been written.  Find the "; horizLine" comment
  1496.      near the top of the source file.  Change the "0" to the left
  1497.      of it to the exact name of the new horizLine() routine. 
  1498.      Repeat this procedure if necessary, until the change has
  1499.      been made for every routine contained in the driver.
  1500.  
  1501.      10.  A usable driver must be created from the source code. 
  1502.      This process involves three steps.  First, assemble the .ASM
  1503.      source file to an .OBJ object file.  Then, link the .OBJ so
  1504.      it becomes an .EXE file.  Third, run EXE2BIN, which comes
  1505.      with DOS.  Assuming the driver's source code was called
  1506.      MYDRV, EXE2BIN's command line would be "EXE2BIN MYDRV.EXE
  1507.      MYDRV.DRV".  When this last step is completed, there will be
  1508.      a newly created driver, ready to be loaded and used with
  1509.      TGE.  The file CDRV.BAT is included to automate this chore;
  1510.      it assumes the use of TASM and TLINK.  Note that since 16-
  1511.      bit offsets are used, the final driver may not be larger
  1512.      than 64 Kb (not a likely problem).
  1513.  
  1514.  
  1515.  
  1516. TERMS OF USAGE AND DISTRIBUTION
  1517. ───────────────────────────────
  1518.  
  1519.      The Graphics Engine source code and associated documentation
  1520.      are copyright (c) 1993 by Matthew Hildebrand.
  1521.  
  1522.      The Graphics Engine, consisting of the files listed in the
  1523.      PACKING LIST section, may be distributed freely, so long as:
  1524.           1.   The distributed package is complete, and its
  1525.                contents are not modified in any way.
  1526.           2.   The distributed package is not sold for profit.
  1527.  
  1528.      The Graphics Engine is not free; no part of it may be used
  1529.      in any program without first purchasing it.  After an
  1530.      individual or organization ("the Purchaser") has purchased a
  1531.      copy of The Graphics Engine, the Purchaser is granted
  1532.      permission to:
  1533.           1.   Use any or all of The Graphics Engine in as many
  1534.                software packages as the Purchaser likes.
  1535.           2.   Distribute any software packages built using The
  1536.                Graphics Engine without royalties.
  1537.           3.   Modify any of the program code, and use the
  1538.                modified code as described in 1 and 2 above.
  1539.      Note that the Purchaser is granted permission to use any
  1540.      version of The Graphics Engine, including any new ones when
  1541.      they are released; ie., upgrades are free.
  1542.  
  1543.      The privileges granted to the Purchaser by purchasing The
  1544.      Graphics Engine may be retracted if any of the following
  1545.      conditions is broken:
  1546.           1.   The copyright notice, which reads "The Graphics
  1547.                Engine 1.20 -- Copyright (c) 1993 by Matthew
  1548.                Hildebrand" must be included in the executable
  1549.                portion of any software package built using it, as
  1550.                well as in any driver files (designed to work with
  1551.                The Graphics Engine) which are part of that
  1552.                software package.  The file TGE.C, as it is
  1553.                shipped, contains this notice, as do the sources
  1554.                for the drivers.
  1555.           2.   Any program code derived or directly obtained from
  1556.                The Graphics Engine may not be distributed in any
  1557.                way, unless the recipient has also purchased a
  1558.                copy of The Graphics Engine.
  1559.           3.   Permission is granted to use The Graphics Engine
  1560.                to create executable software applications; The
  1561.                Graphics Engine may not be used in the creation of
  1562.                another graphics library, unless prior written
  1563.                consent is obtained from the author of The
  1564.                Graphics Engine.
  1565.  
  1566.      In order to purchase a copy of The Graphics Engine, send $25
  1567.      (US or Canadian funds) to Matthew Hildebrand at the address
  1568.      listed in CONTACTING THE AUTHOR below.  Payment by money
  1569.      order, check, or cash is acceptable.  The file REGISTER.FRM
  1570.      is provided for both your convenience and mine; it is
  1571.      designed to be printed out and filled in.  Thank you in
  1572.      advance.
  1573.  
  1574.  
  1575.  
  1576. CONTACTING THE AUTHOR
  1577. ─────────────────────
  1578.  
  1579.      I would appreciate hearing any questions, comments, bug
  1580.      reports, or suggestions for improvement.  If you have any,
  1581.      feel free to contact me.  I can be reached at either of the
  1582.      following addresses.  Contributions of any kind to help
  1583.      improve this project are welcome.  When reporting bugs,
  1584.      please be sure to mention the version of TGE to which you
  1585.      are referring.
  1586.  
  1587.  
  1588.      Snail mail:
  1589.           Matthew Hildebrand
  1590.           4 College St.
  1591.           St. Catharines, ON
  1592.           Canada
  1593.           L2R 2W7 
  1594.  
  1595.      Fidonet mail:
  1596.           1:247/128.2
  1597.  
  1598.      Internet mail:      (no guarantees on this one!)
  1599.           Matthew.Hildebrand@p2.f128.n247.z1.fidonet.org
  1600.  
  1601.  
  1602.  
  1603. OBTAINING THE GRAPHICS ENGINE
  1604. ─────────────────────────────
  1605.  
  1606.      The most recent copy of TGE may be obtained via file request
  1607.      from 1:247/128 (14400 bps V.32bis) using the magic file name
  1608.      "TGE"; unlisted nodes and points are welcome.
  1609.  
  1610.      TGE is also available via first-call download from 1:247/128
  1611.      at (416)-935-6628.  (After October, 1993, the area code will
  1612.      change to 905.)
  1613.  
  1614.  
  1615.  
  1616. REVISION HISTORY
  1617. ────────────────
  1618.  
  1619.      1.20      Added support for loadable fonts, viewports,
  1620.                colour approximation, and region fills.
  1621.  
  1622.                Rewrote the loadGraphDriver() function; it now
  1623.                returns more descriptive values.
  1624.  
  1625.                Added various clipping routines:  clipLine() and
  1626.                clipFilledRect() in CLIP.C, and clipPoint() and
  1627.                pointOnScreen() as macros in TGE.H.
  1628.  
  1629.                Fixed aspect ratio problem in 360x480 driver.
  1630.  
  1631.                Fixed bug in 800x600 driver when run with the
  1632.                Trident 8900 chipset.
  1633.  
  1634.                Added the REGISTER.FRM file.
  1635.  
  1636.      1.10      Improved and debugged SuperVGA support.  Bugs
  1637.                squashed include the infamous Trident and Oak
  1638.                bugs.
  1639.  
  1640.                Added drivers for VGA 360x480 and SuperVGA
  1641.                1024x768.
  1642.  
  1643.                Added interrupt-driven definable mouse pointer
  1644.                services, as well as miscellaneous mouse routines.
  1645.  
  1646.                Fixed default palette routines to do translation
  1647.                between 6-bit and 8-bit values.
  1648.  
  1649.                Added ellipse(), filledEllipse(), circle(), and
  1650.                filledCircle().
  1651.  
  1652.                Added PCX2RAW, a utility to convert 256-colour PCX
  1653.                files into raw bitmap and raw palette files.  This
  1654.                utility makes importing graphics easy.
  1655.  
  1656.      1.01      First public release.
  1657.  
  1658.  
  1659.  
  1660. ACKNOWLEDGEMENT
  1661. ───────────────
  1662.  
  1663.      There are many people whom I would like to thank for their
  1664.      suggestions, beta-testing, patience, and help with
  1665.      distribution.  You know who you are.
  1666.  
  1667.  
  1668.  
  1669. LEGAL MUMBO JUMBO
  1670. ─────────────────
  1671.  
  1672.      All software and documentation associated with The Graphics
  1673.      Engine is provided "as is", and without warranty of any
  1674.      kind.  The author may not be held liable for any damage or
  1675.      misfortune that the usage of this software may cause. 
  1676.      Although the software has undergone extensive testing, there
  1677.      is a chance that it may crash anyway.  It is not even
  1678.      guaranteed to do anything.
  1679.  
  1680.      All registered trademarks in this document belong to
  1681.      whomever it is that owns them.
  1682.